% !TeX root = ../exam-zh-doc-basic.tex

\section{常见问题 FAQ}

本章收集了用户在使用 \cls{exam-zh} 时最常遇到的问题。建议遇到问题时先在这里查找答案。

\subsection{安装与编译问题}

\subsubsection{Q1: 如何确认 exam-zh 安装成功？}

创建一个测试文件，输入：

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}
  \begin{document}
    测试成功
  \end{document}
\end{latexcode}

使用 \cmd{xelatex} 编译，如果生成 PDF 并显示"测试成功"，说明安装成功。

\subsubsection{Q2: 数学公式编译错误}

\textbf{错误原因：}在普通文本中使用了数学符号但没有用 |$| 包裹。编译时会提示 "Missing \$ inserted"。

\textbf{错误示例：}

\begin{latexcode}
  计算结果是 x^2  % 错误：x^2 是数学符号
\end{latexcode}

\textbf{正确写法：}

\begin{latexcode}
  计算结果是 $x^2$  % 正确：用 $ $ 包裹数学公式
\end{latexcode}

\subsubsection{Q3: 中文无法显示或显示乱码}

\textbf{可能原因及解决方案：}

\begin{enumerate}
  \item \textbf{使用了错误的编译器}
    \begin{itemize}
      \item 必须使用 \cmd{xelatex}，不能用 \cmd{pdflatex}
      \item 检查 IDE 设置或命令行命令
    \end{itemize}

  \item \textbf{文件编码不是 UTF-8}
    \begin{itemize}
      \item 确保源文件以 UTF-8 编码保存
      \item 大多数现代编辑器默认 UTF-8，旧版 Windows 记事本可能不是
    \end{itemize}

  \item \textbf{缺少中文字体}
    \begin{itemize}
      \item \TeX{} Live 通常自带中文字体
      \item 可以手动指定字体：\cmd{\textbackslash{}setCJKmainfont\{SimSun\}}
    \end{itemize}
\end{enumerate}

\subsubsection{Q4: 为什么必须用 XeLaTeX？}

\textbf{原因：}

\begin{itemize}
  \item \XeLaTeX{} 原生支持 Unicode，能正确处理中文
  \item 可以直接使用系统字体
  \item 支持现代 OpenType 字体特性
  \item \pdfLaTeX{} 对中文支持较差，需要复杂配置
\end{itemize}

\subsubsection{Q5: 如何在 Overleaf 上使用？}

在文档\textbf{最开头}添加一行代码：

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \let\stop\empty  % 添加这一行
  \documentclass{exam-zh}
  % ... 其余内容
\end{latexcode}

然后在 Overleaf 中选择 \XeLaTeX{} 编译器。

\subsubsection{Q6: TeX Live 2020/2021 编译失败怎么办？}

\textbf{错误现象：}编译时提示 |LaTeX3 Error: The key property '.str_set:N' is unknown|

\textbf{原因：}\LaTeX3 版本过旧，与 \cls{exam-zh} 不兼容。

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{升级到 \TeX{} Live 2022 或更新版本}（推荐）
    \begin{shellcode}[morekeywords={tlmgr,update}]
  # 更新 TeX Live 管理器
  tlmgr update --self --all
    \end{shellcode}

  \item \textbf{或者升级 \LaTeX3 核心包}
    \begin{shellcode}[morekeywords={tlmgr,update}]
  tlmgr update l3kernel l3packages
    \end{shellcode}
\end{enumerate}

\textbf{推荐：}使用 \TeX{} Live 2023 或 2024 以获得最佳兼容性。

\subsubsection{Q7: latexmk 编译陷入无限循环}

\textbf{问题：}使用 |latexmk -xelatex| 命令编译时，程序不停地重复编译。

\textbf{原因：}某些版本的 \cls{exam-zh} 存在辅助文件处理 bug。

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{更新到最新版本}
    \begin{shellcode}[morekeywords={tlmgr,update}]
  tlmgr update exam-zh
    \end{shellcode}

  \item \textbf{或使用手动编译}
    \begin{shellcode}[morekeywords={xelatex}]
  xelatex yourfile.tex
  xelatex yourfile.tex  # 编译两次以更新目录和引用
    \end{shellcode}
\end{enumerate}

\subsubsection{Q8: 找不到 LiSu（隶书）字体}

\textbf{错误信息：}|! Package fontspec Error: The font "LiSu" cannot be found.|

\textbf{原因：}系统缺少隶书字体（常见于 Linux 或精简版 Windows）。

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{安装字体}（Windows 用户）
    \begin{itemize}
      \item 从 C:\textbackslash{}Windows\textbackslash{}Fonts 复制 SIMLI.TTF
      \item 或从网上下载并安装
    \end{itemize}

  \item \textbf{更换字体配置}
    \begin{latexcode}
  % 在文档开头添加
  \setCJKfamilyfont{zhli}{SimSun}  % 用宋体替代隶书
    \end{latexcode}

  \item \textbf{禁用装饰字体}
    \begin{latexcode}
  \examsetup{
    page/show-chapter-label = false  % 不显示需要隶书的章节标签
  }
    \end{latexcode}
\end{enumerate}

\subsubsection{Q9: 2025-10-09 LaTeX3 更新后 choices 环境失效 ⚠️}

\textbf{问题：}2025 年 10 月后，选择题选项无法正常排版，编译报错或选项显示异常。

\textbf{原因：}\LaTeX3 内核更新导致兼容性问题（Issue \#ID3FX0）。

\textbf{临时解决方案：}

\begin{enumerate}
  \item \textbf{降级 \LaTeX3 核心包}（临时）
    \begin{shellcode}[morekeywords={tlmgr,install}]
  # 回退到 2025-09-01 版本
  tlmgr install l3kernel@2025-09-01
    \end{shellcode}

  \item \textbf{使用旧版 \TeX{} Live}
    \begin{itemize}
      \item 如果可能，使用 \TeX{} Live 2024 或更早版本
    \end{itemize}
\end{enumerate}

\textbf{注意：}由于项目已停止维护，此问题可能无官方修复。详见"已知问题与限制"章节。


\subsection{功能使用问题}

\subsubsection{Q10: 如何控制选项列数？}

\textbf{自动模式（推荐）：}

选项会根据内容长度自动排列，无需手动设置。

\textbf{手动指定：}

\begin{latexcode}
  \examsetup{
    choices/columns = 2  % 强制排成2列
  }
\end{latexcode}

或者只对某一题设置：

\begin{latexcode}
  \begin{choices}[columns = 4]  % 这一题排成4列
    \item ...
  \end{choices}
\end{latexcode}

\subsubsection{Q11: 如何生成教师版和学生版？}

\textbf{方法一：}通过注释切换

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}

  % 显示答案（教师版）
  \examsetup{
    paren/show-paren = true,
    question/show-answer = true
  }

  % 隐藏答案（学生版）- 注释掉上面的 \examsetup 即可
\end{latexcode}

\textbf{方法二：}使用条件编译（高级）

在文档开头定义：

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}

  \newif\ifteacher  % 定义教师版开关
  \teachertrue      % 教师版：改为 \teachertrue
  % \teacherfalse   % 学生版：改为 \teacherfalse

  \ifteacher
    \examsetup{
      paren/show-paren = true,
      question/show-answer = true
    }
  \fi
\end{latexcode}

\subsubsection{Q12: 填空题下划线长度如何调整？}

\textbf{全局设置：}

\begin{latexcode}
  \examsetup{
    fillin/width = 4em  % 设置默认宽度为 4em
  }
\end{latexcode}

\textbf{单独设置：}

\begin{latexcode}
  \fillin[width = 6em][答案]  % 这个填空宽度是 6em
\end{latexcode}

\subsubsection{Q13: 如何修改密封线样式？}

\textbf{完全隐藏密封线：}

\begin{latexcode}
  \examsetup{
    page/show-seal-line = false
  }
\end{latexcode}

\textbf{调整密封线位置和样式：}

\begin{latexcode}
  \examsetup{
    seal-line/odd-show = true,     % 奇数页显示
    seal-line/even-show = false,   % 偶数页隐藏
    seal-line/scope = firstpage,   % 只在第一页显示
    seal-line/line-thickness = 1pt,  % 线条粗细
    seal-line/text = {密封线内不要答题},  % 文字内容
  }
\end{latexcode}

详细说明见完整文档。

\subsubsection{Q14: 分值不显示怎么办？}

\textbf{问题：}设置了 \cmd{[points = 10]} 但看不到分值。

\textbf{原因：}默认不显示分值。

\textbf{解决：}

\begin{latexcode}
  \examsetup{
    question/show-points = true  % 显示分值
  }
\end{latexcode}

\subsubsection{Q15: 如何实现答案后置/集中显示？}

\textbf{需求：}希望选择题答案 |\paren[]| 和填空题答案 |\fillin[]| 能像解答题一样，集中显示在试卷末尾。

\textbf{当前状态：}\cls{exam-zh} 目前\textbf{不支持}此功能（Issue \#ICMVN4, \#I5J7YG）。

\textbf{临时解决方案：}

\begin{enumerate}
  \item \textbf{手动整理答案}
    \begin{latexcode}
  % 在文档末尾添加答案页
  \newpage
  \section*{参考答案}
  \begin{enumerate}
    \item C  % 第1题答案
    \item B  % 第2题答案
    \item 3.14  % 第3题填空答案
  \end{enumerate}
    \end{latexcode}

  \item \textbf{使用注释记录}
    \begin{latexcode}
  \begin{question}
    $1 + 1 = $ \paren[C]  % 答案：C
    \begin{choices}
      \item $0$ \item $1$ \item $2$ \item $3$
    \end{choices}
  \end{question}
    \end{latexcode}
    然后手动提取注释中的答案。
\end{enumerate}

\textbf{注意：}由于项目已停止维护，该功能可能不会实现。


\subsection{排版问题}

\subsubsection{Q16: 题号对齐不整齐}

\textbf{问题：}题号1和题号10的宽度不同，导致题干对齐不一致。

\textbf{解决：}设置题号的最宽标签

\begin{latexcode}
  \examsetup{
    question/number-format = \arabic*.,  % 题号格式
    question/label-width = 2.5em,        % 题号宽度（根据最大题号调整）
  }
\end{latexcode}

\subsubsection{Q17: 填空题下划线超出页面边界}

\textbf{问题：}填空题答案较长时，下划线不自动换行，超出页面右边界（Issue \#IAXE1N）。

\textbf{原因：}当前版本填空题下划线不支持自动换行。

\textbf{临时解决方案：}

\begin{enumerate}
  \item \textbf{手动控制宽度}
    \begin{latexcode}
  计算结果为 \fillin[width = 5em][很长的答案]
    \end{latexcode}

  \item \textbf{缩短答案文本}
    \begin{itemize}
      \item 教师版显示时可能需要精简答案
      \item 或使用数学符号代替文字
    \end{itemize}

  \item \textbf{分多个填空}
    \begin{latexcode}
  前半部分 \fillin[答案1]，后半部分 \fillin[答案2]
    \end{latexcode}
\end{enumerate}

\textbf{注意：}此问题暂无完美解决方案，见"已知问题与限制"章节。

\subsubsection{Q18: 填空题答案中使用区间符号 [2,3) 报错}

\textbf{错误信息：}使用 |\fillin[[2,3)]| 时编译报错。

\textbf{原因：}方括号 |[]| 被解析为可选参数的定界符，与答案内容的括号冲突。

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{用花括号包裹答案}（推荐）
    \begin{latexcode}
  答案是 \fillin[{$[2,3)$}]
    \end{latexcode}

  \item \textbf{使用星号变体}
    \begin{latexcode}
  答案是 \fillin*{$[2,3)$}  % 仅教师版显示
    \end{latexcode}

  \item \textbf{避免使用方括号}
    \begin{latexcode}
  答案是 \fillin[$\{2 \leq x < 3\}$]  % 用集合表示
    \end{latexcode}
\end{enumerate}

\subsubsection{Q19: wrapstuff 图文绕排在复杂环境中报错}

\textbf{问题：}在 |problem| 环境内使用两层 |enumerate| 后，|\wrapstuff| 命令报错（Issue \#ID3UMZ）。

\textbf{错误示例：}

\begin{latexcode}
  \begin{problem}
    \begin{enumerate}
      \item 第一问
        \begin{enumerate}
          \item 小问 (a)
            \begin{wrapstuff}  % 此处会报错
              \includegraphics{fig.png}
            \end{wrapstuff}
        \end{enumerate}
    \end{enumerate}
  \end{problem}
\end{latexcode}

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{避免过度嵌套}：不要在两层以上的列表环境中使用图文绕排

  \item \textbf{使用 minipage}（推荐）
    \begin{latexcode}
  \begin{minipage}[t]{0.6\linewidth}
    题目文字内容...
  \end{minipage}%
  \begin{minipage}[t]{0.35\linewidth}
    \includegraphics[width=\linewidth]{fig.png}
  \end{minipage}
    \end{latexcode}

  \item \textbf{将图片放在环境外部}：先结束嵌套环境，再插入图片
\end{enumerate}

\textbf{注意：}此为已知限制，详见"已知问题与限制"章节。

\subsubsection{Q20: 自动换页后行距变大}

\textbf{问题：}偶尔在自动换页时，新页面的行距异常增大（Issue \#I7QTGG）。

\textbf{原因：}\LaTeX{} 的页面垂直对齐机制导致，无法完全避免。

\textbf{临时解决方案：}

\begin{enumerate}
  \item \textbf{手动调整}
    \begin{latexcode}
  % 在行距变大的地方添加
  \vspace{-1em}  % 调整负间距
    \end{latexcode}

  \item \textbf{强制换页}
    \begin{latexcode}
  % 在合适的位置手动换页
  \newpage
    \end{latexcode}

  \item \textbf{调整内容}：删减或增加部分内容，改变自然换页位置
\end{enumerate}

\subsubsection{Q21: 如何整体缩小行距以节约纸张？}

\textbf{需求：}让试卷排版更紧凑，节约打印纸张（Issue \#I9T0DX）。

\textbf{全局调整行距：}

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}

  % 方法1：使用 \linespread
  \linespread{0.9}  % 行距缩小到 90%

  % 方法2：使用 setspace 宏包
  \usepackage{setspace}
  \setstretch{0.85}  % 更精细的控制
\end{latexcode}

\textbf{调整题目间距：}

\begin{latexcode}
  \examsetup{
    question/sep = 0.5em,  % 题目之间的间距（默认 1em）
  }
\end{latexcode}

\textbf{调整选项间距：}

\begin{latexcode}
  \examsetup{
    choices/vsep = 0.3em,  % 选项垂直间距
  }
\end{latexcode}

\textbf{注意：}行距过小可能影响阅读体验，建议不要低于 0.8。

\subsubsection{Q22: 选项自动换行出问题}

\textbf{问题：}选项内容很长，自动换行后排版混乱。

\textbf{建议：}

\begin{enumerate}
  \item 精简选项文字
  \item 手动设置为单列：|\begin{choices}[columns = 1]|
  \item 使用 \cmd{linebreak} 手动换行
\end{enumerate}

\subsubsection{Q23: 数学公式显示异常}

\textbf{常见问题：}

\begin{enumerate}
  \item \textbf{公式不显示}
    \begin{itemize}
      \item 检查是否用 \$ 包裹公式
      \item 例如：|\$x^2\$| 而不是 |x^2|
    \end{itemize}

  \item \textbf{公式中中文不显示}
    \begin{itemize}
      \item 使用 |\text{}| 包裹中文
      \item 例如：|\$x > 0\text{时}\$|
    \end{itemize}

  \item \textbf{分数不显示}
    \begin{itemize}
      \item 使用 |\frac{分子}{分母}|
      \item 例如：|\$\frac{1}{2}\$|
    \end{itemize}
\end{enumerate}

\subsubsection{Q24: \textbackslash Omega 或 \textbackslash varnothing 等数学符号显示异常}

\textbf{问题：}某些希腊字母或特殊数学符号显示不正确或缺失（Issue \#I6W4DR, \#I6VZ17）。

\textbf{原因：}数学字体配置问题。

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{更换数学字体}
    \begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}

  \examsetup{
    math-font = xits,  % 或 tex-gyre-termes, lm
  }
    \end{latexcode}

  \item \textbf{使用替代符号}
    \begin{itemize}
      \item |\varnothing| 显示异常时，使用 |\emptyset|
      \item |\Omega| 有问题时，尝试 |\upOmega| 或 |\mathrm{\Omega}|
    \end{itemize}

  \item \textbf{手动设置字体}（高级）
    \begin{latexcode}
  \usepackage{unicode-math}
  \setmathfont{XITS Math}[range={\Omega,\varnothing}]
    \end{latexcode}
\end{enumerate}

\subsubsection{Q25: 概率统计中波浪号 \textasciitilde{} 无法使用}

\textbf{问题：}在数学模式中输入 |X ~ N(0,1)| 时报错或显示异常（Issue \#I6Z0MD）。

\textbf{原因：}|\~| 是特殊字符，表示上标波浪号或不间断空格。

\textbf{解决方案：}

\begin{latexcode}
  % 错误写法
  $X ~ N(0,1)$

  % 正确写法：使用 \sim 命令
  $X \sim N(0,1)$

  % 或使用 \thicksim（更粗的波浪号）
  $X \thicksim N(0,1)$
\end{latexcode}

\subsubsection{Q26: 向量箭头样式调整}

\textbf{需求：}希望区分大小写字母的向量箭头长度（Issue \#I6NVYF）。

\textbf{当前状态：}\cls{exam-zh} 使用统一的向量箭头样式。

\textbf{自定义解决方案：}

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}

  \usepackage{esvect}  % 更灵活的向量箭头

  % 重定义 \vec 命令，根据字母大小写判断
  \ExplSyntaxOn
  \RenewDocumentCommand{\vec}{m}{
    \str_if_eq:nVTF {#1} { \str_uppercase:n {#1} }
      { \vv*{#1} }  % 大写字母用长箭头
      { \vv{#1} }   % 小写字母用普通箭头
  }
  \ExplSyntaxOff
\end{latexcode}

\textbf{注意：}此为高级用法，需要对 \LaTeX3 有一定了解。

\subsubsection{Q27: 与 listings 或其他代码环境冲突}

\textbf{问题：}在选择题或题目中使用 |lstlisting| 等代码环境时报错（Issue \#I78F7X, \#I8QVL9）。

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{更新到最新版本}：部分兼容性问题已在新版本中修复

  \item \textbf{使用 verbatim 代替}
    \begin{latexcode}
  \begin{question}
    以下代码的输出是：\paren[B]
    \begin{verbatim}
print("Hello")
    \end{verbatim}
  \end{question}
    \end{latexcode}

  \item \textbf{使用 listings 的内联模式}
    \begin{latexcode}
  \begin{question}
    命令 \lstinline|print("Hello")| 的作用是？
  \end{question}
    \end{latexcode}
\end{enumerate}

\subsubsection{Q28: 与 siunitx 宏包的兼容性}

\textbf{问题：}同时使用 |\fillin*| 星号变体和 |siunitx| 宏包时冲突（Issue \#I62TYT）。

\textbf{解决方案：}

\begin{enumerate}
  \item \textbf{避免星号变体}：使用普通的 |\fillin[]| 命令

  \item \textbf{调整加载顺序}
    \begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}

  % 先加载 exam-zh，再加载 siunitx
  \usepackage{siunitx}
    \end{latexcode}
\end{enumerate}

\subsubsection{Q29: 如何插入图片？}

\textbf{基本用法：}

\begin{latexcode}
  \usepackage{graphicx}  % 添加到文档开头

  % 插入图片
  \includegraphics[width=5cm]{图片文件名.jpg}
\end{latexcode}

\textbf{在题目中使用：}

\begin{latexcode}
  \begin{question}
    如图所示，计算三角形面积。
    \begin{center}
      \includegraphics[width=4cm]{triangle.pdf}
    \end{center}
  \end{question}
\end{latexcode}

\textbf{图文混排：}

参考完整文档中"图文排版"章节。

\subsubsection{Q30: 如何调整页边距？}

\textbf{全局设置：}

\begin{latexcode}[deletetexcs={\documentclass},morekeywords={\documentclass}]
  \documentclass{exam-zh}

  \usepackage{geometry}
  \geometry{
    top = 2.5cm,
    bottom = 2cm,
    left = 2cm,
    right = 2cm
  }
\end{latexcode}

\textbf{使用预设：}

\begin{latexcode}
  \examsetup{
    page/size = a4paper,  % 纸张大小
  }
\end{latexcode}


\subsection{获取帮助}

如果以上 FAQ 没有解决你的问题，可以通过以下方式获取帮助：

\subsubsection{查阅文档}

\begin{enumerate}
  \item \textbf{本文档}：\file{exam-zh-doc-basic.pdf}（入门指南）
  \item \textbf{完整文档}：\file{exam-zh-doc.pdf}（详细 API 参考）
  \item \textbf{LaTeX 入门}：\href{https://ctan.org/pkg/lshort-chinese}{lshort-zh-cn}
\end{enumerate}

\subsubsection{在线提问}

\textbf{GitHub/Gitee Issues：}

\begin{itemize}
  \item GitHub: \url{https://github.com/xkwxdyy/exam-zh/issues}
  \item Gitee: \url{https://gitee.com/xkwxdyy/exam-zh/issues}
\end{itemize}

\textbf{QQ 群：}652500180

\subsubsection{提问前的准备}

为了快速得到帮助，提问时请提供：

\begin{enumerate}
  \item \textbf{系统信息}：操作系统、\TeX{} 发行版版本
  \item \textbf{问题描述}：清楚描述遇到的问题
  \item \textbf{最小可复现示例}：能重现问题的最简代码
  \item \textbf{错误信息}：完整的错误提示（\emph{请勿用手机拍照}）
  \item \textbf{期望结果}：你想要达到的效果
\end{enumerate}

\textbf{提问模板：}

\begin{latexcode}
  系统：macOS / Windows / Linux
  TeX 发行版：TeX Live 2024
  exam-zh 版本：v0.26

  问题描述：
    我想实现...，但是出现了...

  最小可复现代码：
    \documentclass{exam-zh}
    \begin{document}
      ...（能重现问题的代码）
    \end{document}

  错误信息：
    ...（复制粘贴错误文本）

  期望效果：
    我希望能...
\end{latexcode}

详细的提问指南见附录"如何提问"。
